home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / p_man / cat3 / Xm / XmQTtransfer.z / XmQTtransfer
Text File  |  1998-10-30  |  38KB  |  529 lines
  1.  
  2.  
  3.  
  4.      XXXXmmmmQQQQTTTTttttrrrraaaannnnssssffffeeeerrrr((((3333XXXX))))          UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV          XXXXmmmmQQQQTTTTttttrrrraaaannnnssssffffeeeerrrr((((3333XXXX))))
  5.  
  6.  
  7.  
  8.      NNNNAAAAMMMMEEEE
  9.           _X_m_Q_T_t_r_a_n_s_f_e_r - A trait that implements data transfer to and
  10.           from a widget
  11.  
  12.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.           #include <Xm/TransferT.h>
  14.  
  15.           typedef struct {
  16.                     int                             version;
  17.                     XmConvertCallbackProc           convertProc;
  18.                     XmDestinationCallbackProc       destinationProc;
  19.                     XmDestinationCallbackProc       destinationPreHookProc;
  20.           } XmTransferTraitRec, *XmTransferTrait;
  21.           vvvvooooiiiidddd ((((****XXXXmmmmCCCCoooonnnnvvvveeeerrrrttttCCCCaaaallllllllbbbbaaaacccckkkkPPPPrrrroooocccc))))(
  22.           WWWWiiiiddddggggeeeetttt,
  23.           XXXXttttPPPPooooiiiinnnntttteeeerrrr,
  24.           XXXXttttPPPPooooiiiinnnntttteeeerrrr,
  25.           vvvvooooiiiidddd ((((****XXXXmmmmDDDDeeeessssttttiiiinnnnaaaattttiiiioooonnnnCCCCaaaallllllllbbbbaaaacccckkkkPPPPrrrroooocccc))))(
  26.           WWWWiiiiddddggggeeeetttt,
  27.           XXXXttttPPPPooooiiiinnnntttteeeerrrr,
  28.           XXXXttttPPPPooooiiiinnnntttteeeerrrr);
  29.  
  30.      VVVVEEEERRRRSSSSIIIIOOOONNNN
  31.           This page documents Motif 2.1.
  32.  
  33.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  34.           The _X_m_Q_T_t_r_a_n_s_f_e_r trait is installed on any widget that can
  35.           be a source or destination for data transfer.  The usual
  36.           means of transferring data is the conversion of a selection.
  37.           The selections supported by Motif are _P_R_I_M_A_R_Y, _S_E_C_O_N_D_A_R_Y,
  38.           _C_L_I_P_B_O_A_R_D, and ____MMMMOOOOTTTTIIIIFFFF____DDDDRRRROOOOPPPP (for drag and drop operations).
  39.           A widget can be the source or destination for zero or more
  40.           of these selections.
  41.  
  42.           If your widget is to be a source of data in a transfer, then
  43.           your widget must supply a ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc trait method.  This
  44.           trait method is responsible for converting data to a
  45.           requested target.  If your widget is to be a data transfer
  46.           destination, then your widget must supply a ddddeeeessssttttiiiinnnnaaaattttiiiioooonnnnPPPPrrrroooocccc
  47.           trait method and can optionally supply a
  48.           ddddeeeessssttttiiiinnnnaaaattttiiiinnnnooooPPPPrrrreeeeHHHHooooooookkkkPPPPrrrroooocccc trait method.  The ddddeeeessssttttiiiinnnnaaaattttiiiioooonnnnPPPPrrrroooocccc
  49.           trait method is responsible for requesting target(s) from
  50.           the source and for providing the name of a transfer
  51.           procedure to handle the returned data.  The
  52.           ddddeeeessssttttiiiinnnnaaaattttiiiioooonnnnPPPPrrrreeeeHHHHooooooookkkkPPPPrrrroooocccc trait method is used to prepare data
  53.           for the ddddeeeessssttttiiiinnnnaaaattttiiiioooonnnnPPPPrrrroooocccc method.
  54.  
  55.           The standard Motif widgets XXXXmmmmCCCCoooonnnnttttaaaaiiiinnnneeeerrrr, XXXXmmmmLLLLaaaabbbbeeeellll,
  56.           XXXXmmmmLLLLaaaabbbbeeeellllGGGGaaaaddddggggeeeetttt, XXXXmmmmLLLLiiiisssstttt, XXXXmmmmSSSSccccaaaalllleeee, XXXXmmmmTTTTeeeexxxxtttt, and XXXXmmmmTTTTeeeexxxxttttFFFFiiiieeeelllldddd all
  57.           hold this trait.  XXXXmmmmLLLLaaaabbbbeeeellll, XXXXmmmmLLLLaaaabbbbeeeellllGGGGaaaaddddggggeeeetttt, XXXXmmmmLLLLiiiisssstttt, and
  58.           XXXXmmmmSSSSccccaaaalllleeeeprovide only ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc methods.  XXXXmmmmCCCCoooonnnnttttaaaaiiiinnnneeeerrrr,
  59.           XXXXmmmmTTTTeeeexxxxtttt, and XXXXmmmmTTTTeeeexxxxttttFFFFiiiieeeellllddddprovide both ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc and
  60.  
  61.  
  62.  
  63.      Page 1                                         (printed 10/24/98)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      XXXXmmmmQQQQTTTTttttrrrraaaannnnssssffffeeeerrrr((((3333XXXX))))          UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV          XXXXmmmmQQQQTTTTttttrrrraaaannnnssssffffeeeerrrr((((3333XXXX))))
  71.  
  72.  
  73.  
  74.           ddddeeeessssttttiiiinnnnaaaattttiiiioooonnnnPPPPrrrroooocccc methods.
  75.  
  76.           (See the _E_x_m_S_t_r_i_n_g_T_r_a_n_s_f_e_r demonstration widget in the
  77.           ddddeeeemmmmoooossss////wwwwiiiiddddggggeeeettttssss////EEEExxxxmmmm////lllliiiibbbb directory for an example usage of this
  78.           trait.)
  79.  
  80.         TTTThhhheeee ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc TTTTrrrraaaaiiiitttt MMMMeeeetttthhhhoooodddd
  81.           vvvvooooiiiidddd ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc(
  82.           WWWWiiiiddddggggeeeetttt wwwwiiiiddddggggeeeetttt,
  83.           XXXXttttPPPPooooiiiinnnntttteeeerrrr cccclllliiiieeeennnntttt____ddddaaaattttaaaa,
  84.           XXXXttttPPPPooooiiiinnnntttteeeerrrr ccccaaaallllllll____ddddaaaattttaaaa);
  85.  
  86.           The ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc method is invoked when the widget is the
  87.           source for a data transfer operation.  This method converts
  88.           a selection to a requested target.  The _c_a_l_l__d_a_t_a argument
  89.           is a pointer to an XXXXmmmmCCCCoooonnnnvvvveeeerrrrttttCCCCaaaallllllllbbbbaaaacccckkkkSSSSttttrrrruuuucccctttt structure.  The
  90.           method typically examines the _s_e_l_e_c_t_i_o_n and _t_a_r_g_e_tmembers of
  91.           this structure.  It returns the converted data in the _v_a_l_u_e
  92.           member and returns an indicator of the conversion status in
  93.           the _s_t_a_t_u_s member.
  94.  
  95.           When the _t_a_r_g_e_t member of the structure is _T_A_R_G_E_T_S, the
  96.           ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc method usually provides data by calling
  97.           XXXXmmmmeeeeSSSSttttaaaannnnddddaaaarrrrddddTTTTaaaarrrrggggeeeettttssss and then adding any targets to which the
  98.           ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc method converts data.  The method can call
  99.           XXXXmmmmeeeeSSSSttttaaaannnnddddaaaarrrrddddCCCCoooonnnnvvvveeeerrrrtttt to convert data to any of the standard
  100.           targets.
  101.  
  102.           The ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc method is invoked after any
  103.           XXXXmmmmNNNNccccoooonnnnvvvveeeerrrrttttCCCCaaaallllllllbbbbaaaacccckkkk procedures are called.  The callback
  104.           procedures can perform all or part of the conversion
  105.           themselves, refuse the conversion, or let the ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc
  106.           method handle the conversion.  If the callback procedures
  107.           perform the complete conversion or refuse the conversion,
  108.           the ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc method is not called.  More specifically,
  109.           the ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc method is not called if, after all callback
  110.           procedures have returned, the value of the _s_t_a_t_u_smember of
  111.           the XXXXmmmmCCCCoooonnnnvvvveeeerrrrttttCCCCaaaallllllllbbbbaaaacccckkkkSSSSttttrrrruuuucccctttt is other than XXXXmmmmCCCCOOOONNNNVVVVEEEERRRRTTTT____DDDDEEEEFFFFAAAAUUUULLLLTTTT
  112.           or XXXXmmmmCCCCOOOONNNNVVVVEEEERRRRTTTT____MMMMEEEERRRRGGGGEEEE.
  113.  
  114.           _w_i_d_g_e_t    Specifies the widget that is asked to convert the
  115.                     data.
  116.  
  117.           _c_l_i_e_n_t__d_a_t_a
  118.                     This argument is currently unused.  The value is
  119.                     always _N_U_L_L.
  120.  
  121.           _c_a_l_l__d_a_t_a Specifies a pointer to an XXXXmmmmCCCCoooonnnnvvvveeeerrrrttttCCCCaaaallllllllbbbbaaaacccckkkkSSSSttttrrrruuuucccctttt
  122.                     structure.
  123.  
  124.           Following is a description of the
  125.           XXXXmmmmCCCCoooonnnnvvvveeeerrrrttttCCCCaaaallllllllbbbbaaaacccckkkkSSSSttttrrrruuuuccccttttstructure:
  126.  
  127.  
  128.  
  129.      Page 2                                         (printed 10/24/98)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      XXXXmmmmQQQQTTTTttttrrrraaaannnnssssffffeeeerrrr((((3333XXXX))))          UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV          XXXXmmmmQQQQTTTTttttrrrraaaannnnssssffffeeeerrrr((((3333XXXX))))
  137.  
  138.  
  139.  
  140.           typedef struct {
  141.                     int       reason;
  142.                     XEvent    *event;
  143.                     Atom      selection;
  144.                     Atom      target;
  145.                     XtPointer       source_data;
  146.                     XtPointer       location_data;
  147.                     int       flag;
  148.                     XtPointer       parm;
  149.                     int       parm_format;
  150.                     unsigned long   parm_length;
  151.                     Atom           parm_type;
  152.                     int       status;
  153.                     XtPointer       value;
  154.                     Atom      type;
  155.                     int       format;
  156.                     unsigned long   length;
  157.           } XmConvertCallbackStruct;
  158.  
  159.           _r_e_a_s_o_n    Indicates why the callback was invoked.
  160.  
  161.           _e_v_e_n_t     Points to the _X_E_v_e_n_t that triggered the callback.
  162.                     It can be _N_U_L_L.
  163.  
  164.           _s_e_l_e_c_t_i_o_n Indicates the selection for which conversion is
  165.                     being requested.  Possible values are _C_L_I_P_B_O_A_R_D,
  166.                     _P_R_I_M_A_R_Y, _S_E_C_O_N_D_A_R_Y, and ____MMMMOOOOTTTTIIIIFFFF____DDDDRRRROOOOPPPP.
  167.  
  168.           _t_a_r_g_e_t    Indicates the conversion target.
  169.  
  170.           _s_o_u_r_c_e__d_a_t_a
  171.                     Contains information about the selection source.
  172.                     When the selection is ____MMMMOOOOTTTTIIIIFFFF____DDDDRRRROOOOPPPP, _s_o_u_r_c_e__d_a_t_a is
  173.                     the DragContext.  Otherwise, it is _N_U_L_L.
  174.  
  175.           _l_o_c_a_t_i_o_n__d_a_t_a
  176.                     Contains information about the location of data to
  177.                     be converted.  If the value is _N_U_L_L, the data to
  178.                     be transferred consists of the widget's current
  179.                     selection.  Otherwise, the type and interpretation
  180.                     of the value are specific to the widget class.
  181.  
  182.           _f_l_a_g      This member is currently unused.
  183.  
  184.           _p_a_r_m      Contains parameter data for this target.  If no
  185.                     parameter data exists, the value is _N_U_L_L.
  186.  
  187.                     When _s_e_l_e_c_t_i_o_n is _C_L_I_P_B_O_A_R_D and _t_a_r_g_e_t is
  188.                     ____MMMMOOOOTTTTIIIIFFFF____CCCCLLLLIIIIPPPPBBBBOOOOAAAARRRRDDDD____TTTTAAAARRRRGGGGEEEETTTTSSSS or
  189.                     ____MMMMOOOOTTTTIIIIFFFF____DDDDEEEEFFFFEEEERRRRRRRREEEEDDDD____CCCCLLLLIIIIPPPPBBBBOOOOAAAARRRRDDDD____TTTTAAAARRRRGGGGEEEETTTTSSSS, the value is
  190.                     the requested operation (XXXXmmmmCCCCOOOOPPPPYYYY, XXXXmmmmMMMMOOOOVVVVEEEE, or
  191.                     XXXXmmmmLLLLIIIINNNNKKKK).
  192.  
  193.  
  194.  
  195.      Page 3                                         (printed 10/24/98)
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.      XXXXmmmmQQQQTTTTttttrrrraaaannnnssssffffeeeerrrr((((3333XXXX))))          UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV          XXXXmmmmQQQQTTTTttttrrrraaaannnnssssffffeeeerrrr((((3333XXXX))))
  203.  
  204.  
  205.  
  206.           _p_a_r_m__f_o_r_m_a_t
  207.                     Specifies whether the data in _p_a_r_m should be
  208.                     viewed as a list of 8-bit, 16-bit, or 32-bit
  209.                     quantities.  Possible values are 0 (when _p_a_r_m is
  210.                     _N_U_L_L), 8, 16, and 32.
  211.  
  212.           _p_a_r_m__l_e_n_g_t_h
  213.                     Specifies the number of elements of data in _p_a_r_m,
  214.                     where each element has the number of bits
  215.                     specified by _p_a_r_m__f_o_r_m_a_t.  When _p_a_r_m is _N_U_L_L, the
  216.                     value is 0.
  217.  
  218.           _p_a_r_m__t_y_p_e Specifies the parameter type of _p_a_r_m.
  219.  
  220.           _s_t_a_t_u_s    An IIIINNNN////OOOOUUUUTTTT member that specifies the status of the
  221.                     conversion.  The initial value set by the toolkit
  222.                     is XXXXmmmmCCCCOOOONNNNVVVVEEEERRRRTTTT____DDDDEEEEFFFFAAAAUUUULLLLTTTT, but an XXXXmmmmNNNNccccoooonnnnvvvveeeerrrrttttCCCCaaaallllllllbbbbaaaacccckkkk
  223.                     procedure may have set a different value.
  224.                     Following are the possible values:
  225.  
  226.                     XXXXmmmmCCCCOOOONNNNVVVVEEEERRRRTTTT____DDDDEEEEFFFFAAAAUUUULLLLTTTT
  227.                               This value means that the ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc
  228.                               trait method, if it wishes, should
  229.                               perform the entire conversion.  If the
  230.                               ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc produces any data, it
  231.                               overwrites the data provided by the
  232.                               callback procedures in the _v_a_l_u_e member.
  233.  
  234.                     XXXXmmmmCCCCOOOONNNNVVVVEEEERRRRTTTT____MMMMEEEERRRRGGGGEEEE
  235.                               This value means that the ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc
  236.                               trait method should merge its converted
  237.                               data, if any, with the data provided by
  238.                               the callback procedures.  If the
  239.                               ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc produces any data, it uses
  240.                               XXXXmmmmeeeeCCCCoooonnnnvvvveeeerrrrttttMMMMeeeerrrrggggeeee to append its data to
  241.                               the data provided by the callback
  242.                               procedures in the _v_a_l_u_e member.  This
  243.                               value is intended for use with targets
  244.                               that result in lists of data, such as
  245.                               _T_A_R_G_E_T_S.
  246.  
  247.                     XXXXmmmmCCCCOOOONNNNVVVVEEEERRRRTTTT____DDDDOOOONNNNEEEE
  248.                               The _s_t_a_t_u_s member never has this value
  249.                               on entry to ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc.  When the
  250.                               ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc trait method finishes a
  251.                               successful conversion, it sets _s_t_a_t_u_s to
  252.                               XXXXmmmmCCCCOOOONNNNVVVVEEEERRRRTTTT____DDDDOOOONNNNEEEE.
  253.  
  254.                     XXXXmmmmCCCCOOOONNNNVVVVEEEERRRRTTTT____RRRREEEEFFFFUUUUSSSSEEEE
  255.                               The _s_t_a_t_u_s member never has this value
  256.                               on entry to the ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc.  When the
  257.                               ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc trait method terminates an
  258.  
  259.  
  260.  
  261.      Page 4                                         (printed 10/24/98)
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.      XXXXmmmmQQQQTTTTttttrrrraaaannnnssssffffeeeerrrr((((3333XXXX))))          UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV          XXXXmmmmQQQQTTTTttttrrrraaaannnnssssffffeeeerrrr((((3333XXXX))))
  269.  
  270.  
  271.  
  272.                               unsuccessful conversion, it sets _s_t_a_t_u_s
  273.                               to XXXXmmmmCCCCOOOONNNNVVVVEEEERRRRTTTT____RRRREEEEFFFFUUUUSSSSEEEE.
  274.  
  275.                     Before returning, the ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc trait method
  276.                     should always set _s_t_a_t_u_sto either XXXXmmmmCCCCOOOONNNNVVVVEEEERRRRTTTT____DDDDOOOONNNNEEEE,
  277.                     indicating a successful conversion, or
  278.                     XXXXmmmmCCCCOOOONNNNVVVVEEEERRRRTTTT____RRRREEEEFFFFUUUUSSSSEEEE, indicating an unsuccessful
  279.                     conversion.
  280.  
  281.           _v_a_l_u_e     An IIIINNNN////OOOOUUUUTTTT parameter that contains any data that
  282.                     the callback procedures or the ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc trait
  283.                     method produces as a result of the conversion.
  284.                     The initial value is _N_U_L_L.  If the ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc
  285.                     trait method sets this member, it must ensure that
  286.                     the _t_y_p_e, _f_o_r_m_a_t, and _l_e_n_g_t_h members correspond to
  287.                     the data in _v_a_l_u_e.  The ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc trait method
  288.                     is responsible for allocating memory when it sets
  289.                     this member.  The toolkit frees this memory when
  290.                     it is no longer needed.
  291.  
  292.           _t_y_p_e      An IIIINNNN////OOOOUUUUTTTT parameter that indicates the type of the
  293.                     data in the _v_a_l_u_e member.  The initial value is
  294.                     _I_N_T_E_G_E_R.
  295.  
  296.           _f_o_r_m_a_t    An IIIINNNN////OOOOUUUUTTTT parameter that specifies whether the
  297.                     data in _v_a_l_u_eshould be viewed as a list of 8-bit,
  298.                     16-bit, or 32-bit quantities.  The initial value
  299.                     is 8888.  The ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc trait method can set this
  300.                     member to 8888, 11116666, or 33332222.
  301.  
  302.           _l_e_n_g_t_h    An IIIINNNN////OOOOUUUUTTTT member that specifies the number of
  303.                     elements of data in _v_a_l_u_e, where each element has
  304.                     the number of bits specified by _f_o_r_m_a_t.  The
  305.                     initial value is 0.
  306.  
  307.         TTTThhhheeee ddddeeeessssttttiiiinnnnaaaattttiiiioooonnnnPPPPrrrroooocccc TTTTrrrraaaaiiiitttt MMMMeeeetttthhhhoooodddd
  308.           vvvvooooiiiidddd ddddeeeessssttttiiiinnnnaaaattttiiiioooonnnnPPPPrrrroooocccc(
  309.           WWWWiiiiddddggggeeeetttt wwwwiiiiddddggggeeeetttt,
  310.           XXXXttttPPPPooooiiiinnnntttteeeerrrr cccclllliiiieeeennnntttt____ddddaaaattttaaaa,
  311.           XXXXttttPPPPooooiiiinnnntttteeeerrrr ccccaaaallllllll____ddddaaaattttaaaa);
  312.  
  313.           The ddddeeeessssttttiiiinnnnaaaattttiiiioooonnnnPPPPrrrroooocccc trait method is invoked when the widget
  314.           is the destination for a data transfer operation.  The
  315.           _c_a_l_l__d_a_t_a argument is a pointer to an
  316.           XXXXmmmmDDDDeeeessssttttiiiinnnnaaaattttiiiioooonnnnCCCCaaaallllllllbbbbaaaacccckkkkSSSSttttrrrruuuucccctttt structure.  This method requests
  317.           conversion of a selection to an appropriate target, usually
  318.           by calling _X_m_T_r_a_n_s_f_e_r_V_a_l_u_e.  The method usually supplies a
  319.           callback to _X_m_T_r_a_n_s_f_e_r_V_a_l_u_e that receives and possibly
  320.           inserts the converted data.  The _X_m_T_r_a_n_s_f_e_r_V_a_l_u_e callback
  321.           returns an indicator of the transfer status.  Either the
  322.           ddddeeeessssttttiiiinnnnaaaattttiiiioooonnnnPPPPrrrroooocccc trait method or the _X_m_T_r_a_n_s_f_e_r_V_a_l_u_ecallback
  323.           can also terminate the transfer operation by calling
  324.  
  325.  
  326.  
  327.      Page 5                                         (printed 10/24/98)
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.      XXXXmmmmQQQQTTTTttttrrrraaaannnnssssffffeeeerrrr((((3333XXXX))))          UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV          XXXXmmmmQQQQTTTTttttrrrraaaannnnssssffffeeeerrrr((((3333XXXX))))
  335.  
  336.  
  337.  
  338.           _X_m_T_r_a_n_s_f_e_r_D_o_n_e.
  339.  
  340.           The ddddeeeessssttttiiiinnnnaaaattttiiiioooonnnnPPPPrrrroooocccc trait method is invoked after any
  341.           XXXXmmmmNNNNddddeeeessssttttiiiinnnnaaaattttiiiioooonnnnCCCCaaaallllllllbbbbaaaacccckkkk procedures are called and after all
  342.           data conversions initiated by those callback procedures are
  343.           complete.  The callback procedures can perform the data
  344.           transfer themselves, refuse the transfer, or let the
  345.           ddddeeeessssttttiiiinnnnaaaattttiiiioooonnnnPPPPrrrroooocccc trait method handle the transfer.  If the
  346.           callback procedures perform the transfer themselves or
  347.           refuse the transfer, the ddddeeeessssttttiiiinnnnaaaattttiiiioooonnnnPPPPrrrroooocccc trait method is not
  348.           called.  More specifically, the ddddeeeessssttttiiiinnnnaaaattttiiiioooonnnnPPPPrrrroooocccc trait method
  349.           is not invoked if a callback procedure has called
  350.           _X_m_T_r_a_n_s_f_e_r_D_o_n_e with a transfer status other than
  351.           XXXXmmmmTTTTRRRRAAAANNNNSSSSFFFFEEEERRRR____DDDDEEEEFFFFAAAAUUUULLLLTTTT.
  352.  
  353.           _w_i_d_g_e_t    Specifies the widget that is the destination for
  354.                     the transfer.
  355.  
  356.           _c_l_i_e_n_t__d_a_t_a
  357.                     This argument is currently unused.  The value is
  358.                     always _N_U_L_L.
  359.  
  360.           _c_a_l_l__d_a_t_a Specifies a pointer to an
  361.                     XXXXmmmmDDDDeeeessssttttiiiinnnnaaaattttiiiioooonnnnCCCCaaaallllllllbbbbaaaacccckkkkSSSSttttrrrruuuucccctttt structure.
  362.  
  363.           Following is a description of the
  364.           XXXXmmmmDDDDeeeessssttttiiiinnnnaaaattttiiiioooonnnnCCCCaaaallllllllbbbbaaaacccckkkkSSSSttttrrrruuuuccccttttstructure:
  365.  
  366.           typedef struct {
  367.                     int       reason;
  368.                     XEvent    *event;
  369.                     Atom      selection;
  370.                     XtEnum    operation;
  371.                     int       flags;
  372.                     XtPointer       transfer_id;
  373.                     XtPointer       destination_data;
  374.                     XtPointer       location_data;
  375.                     Time      time;
  376.           } XmDestinationCallbackStruct;
  377.  
  378.           _r_e_a_s_o_n    Indicates why the callback was invoked.
  379.  
  380.           _e_v_e_n_t     Points to the _X_E_v_e_n_t that triggered the callback.
  381.                     It can be _N_U_L_L.
  382.  
  383.           _s_e_l_e_c_t_i_o_n Indicates the selection for which data transfer is
  384.                     being requested.  Possible values are _C_L_I_P_B_O_A_R_D,
  385.                     _P_R_I_M_A_R_Y, _S_E_C_O_N_D_A_R_Y, and ____MMMMOOOOTTTTIIIIFFFF____DDDDRRRROOOOPPPP.
  386.  
  387.           _o_p_e_r_a_t_i_o_n Indicates the type of transfer operation
  388.                     requested.
  389.  
  390.  
  391.  
  392.  
  393.      Page 6                                         (printed 10/24/98)
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.      XXXXmmmmQQQQTTTTttttrrrraaaannnnssssffffeeeerrrr((((3333XXXX))))          UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV          XXXXmmmmQQQQTTTTttttrrrraaaannnnssssffffeeeerrrr((((3333XXXX))))
  401.  
  402.  
  403.  
  404.                        +o  When the selection is _P_R_I_M_A_R_Y, possible
  405.                           values are XXXXmmmmMMMMOOOOVVVVEEEE, XXXXmmmmCCCCOOOOPPPPYYYY, and XXXXmmmmLLLLIIIINNNNKKKK.
  406.  
  407.                        +o  When the selection is _S_E_C_O_N_D_A_R_Y or
  408.                           _C_L_I_P_B_O_A_R_D, possible values are XXXXmmmmCCCCOOOOPPPPYYYY and
  409.                           XXXXmmmmLLLLIIIINNNNKKKK.
  410.  
  411.                        +o  When the selection is ____MMMMOOOOTTTTIIIIFFFF____DDDDRRRROOOOPPPP, possible
  412.                           values are XXXXmmmmMMMMOOOOVVVVEEEE, XXXXmmmmCCCCOOOOPPPPYYYY, XXXXmmmmLLLLIIIINNNNKKKK, and
  413.                           XXXXmmmmOOOOTTTTHHHHEEEERRRR.  A value of XXXXmmmmOOOOTTTTHHHHEEEERRRR means that the
  414.                           callback procedure must get further
  415.                           information from the
  416.                           XXXXmmmmDDDDrrrrooooppppPPPPrrrrooooccccCCCCaaaallllllllbbbbaaaacccckkkkSSSSttttrrrruuuucccctttt in the
  417.                           _d_e_s_t_i_n_a_t_i_o_n__d_a_t_a member.
  418.  
  419.           _f_l_a_g_s     Indicates whether or not the destination widget is
  420.                     also the source of the data to be transferred.
  421.                     Following are the possible values:
  422.  
  423.                     XXXXmmmmCCCCOOOONNNNVVVVEEEERRRRTTTTIIIINNNNGGGG____NNNNOOOONNNNEEEE
  424.                               The destination widget is not the source
  425.                               of the data to be transferred.
  426.  
  427.                     XXXXmmmmCCCCOOOONNNNVVVVEEEERRRRTTTTIIIINNNNGGGG____SSSSAAAAMMMMEEEE
  428.                               The destination widget is the source of
  429.                               the data to be transferred.
  430.  
  431.           _t_r_a_n_s_f_e_r__i_d
  432.                     Serves as a unique ID to identify the transfer
  433.                     transaction.
  434.  
  435.           _d_e_s_t_i_n_a_t_i_o_n__d_a_t_a
  436.                     Contains information about the destination.  When
  437.                     the selection is ____MMMMOOOOTTTTIIIIFFFF____DDDDRRRROOOOPPPP, the ddddeeeessssttttiiiinnnnaaaattttiiiioooonnnnPPPPrrrroooocccc
  438.                     trait method is called by the drop site's
  439.                     XXXXmmmmNNNNddddrrrrooooppppPPPPrrrroooocccc, and _d_e_s_t_i_n_a_t_i_o_n__d_a_t_ais a pointer to
  440.                     the XXXXmmmmDDDDrrrrooooppppPPPPrrrrooooccccCCCCaaaallllllllbbbbaaaacccckkkkSSSSttttrrrruuuucccctttt passed to the
  441.                     XXXXmmmmNNNNddddrrrrooooppppPPPPrrrroooocccc procedure.  When the selection is
  442.                     _S_E_C_O_N_D_A_R_Y, _d_e_s_t_i_n_a_t_i_o_n__d_a_t_a is an Atom
  443.                     representing a target recommmended by the
  444.                     selection owner for use in converting the
  445.                     selection.  Otherwise, _d_e_s_t_i_n_a_t_i_o_n__d_a_t_a is _N_U_L_L.
  446.  
  447.           _l_o_c_a_t_i_o_n__d_a_t_a
  448.                     Contains information about the location where data
  449.                     is to be transferred.  The value is always _N_U_L_L
  450.                     when the selection is _S_E_C_O_N_D_A_R_Y or _C_L_I_P_B_O_A_R_D.  If
  451.                     the value is _N_U_L_L, the data is to be inserted at
  452.                     the widget's cursor position.  Otherwise, the type
  453.                     and interpretation of the value are specific to
  454.                     the widget class. The value of _l_o_c_a_t_i_o_n__d_a_t_a is
  455.                     only valid for the duration of a transfer. Once
  456.  
  457.  
  458.  
  459.      Page 7                                         (printed 10/24/98)
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.      XXXXmmmmQQQQTTTTttttrrrraaaannnnssssffffeeeerrrr((((3333XXXX))))          UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV          XXXXmmmmQQQQTTTTttttrrrraaaannnnssssffffeeeerrrr((((3333XXXX))))
  467.  
  468.  
  469.  
  470.                     transfer done procedures start to be called,
  471.                     _l_o_c_a_t_i_o_n__d_a_t_a will no longer be stable.
  472.  
  473.           _t_i_m_e      Indicates the time when the transfer operation
  474.                     began.
  475.  
  476.         TTTThhhheeee ddddeeeessssttttiiiinnnnaaaattttiiiioooonnnnPPPPrrrreeeeHHHHooooooookkkkPPPPrrrroooocccc TTTTrrrraaaaiiiitttt MMMMeeeetttthhhhoooodddd
  477.           vvvvooooiiiidddd ddddeeeessssttttiiiinnnnaaaattttiiiioooonnnnPPPPrrrreeeeHHHHooooooookkkkPPPPrrrroooocccc(
  478.           WWWWiiiiddddggggeeeetttt wwwwiiiiddddggggeeeetttt,
  479.           XXXXttttPPPPooooiiiinnnntttteeeerrrr cccclllliiiieeeennnntttt____ddddaaaattttaaaa,
  480.           XXXXttttPPPPooooiiiinnnntttteeeerrrr ccccaaaallllllll____ddddaaaattttaaaa);
  481.  
  482.           The ddddeeeessssttttiiiinnnnaaaattttiiiioooonnnnPPPPrrrreeeeHHHHooooooookkkkPPPPrrrroooocccc trait method is invoked when the
  483.           widget is the destination for a data transfer operation.
  484.           This method is called before any XXXXmmmmNNNNddddeeeessssttttiiiinnnnaaaattttiiiioooonnnnCCCCaaaallllllllbbbbaaaacccckkkk
  485.           procedures are invoked.  The _c_a_l_l__d_a_t_a argument is a pointer
  486.           to an XXXXmmmmDDDDeeeessssttttiiiinnnnaaaattttiiiioooonnnnCCCCaaaallllllllbbbbaaaacccckkkkSSSSttttrrrruuuucccctttt structure.  The method can
  487.           provide any information, such as a value for the
  488.           _l_o_c_a_t_i_o_n__d_a_t_a member of the structure, that the
  489.           XXXXmmmmNNNNddddeeeessssttttiiiinnnnaaaattttiiiioooonnnnCCCCaaaallllllllbbbbaaaacccckkkk procedures or the
  490.           ddddeeeessssttttiiiinnnnaaaattttiiiioooonnnnPPPPrrrroooocccctrait method may need.
  491.  
  492.           _w_i_d_g_e_t    Specifies the widget that is the destination for
  493.                     the transfer.
  494.  
  495.           _c_l_i_e_n_t__d_a_t_a
  496.                     This argument is currently unused.  The value is
  497.                     always _N_U_L_L.
  498.  
  499.           _c_a_l_l__d_a_t_a Specifies a pointer to an
  500.                     XXXXmmmmDDDDeeeessssttttiiiinnnnaaaattttiiiioooonnnnCCCCaaaallllllllbbbbaaaacccckkkkSSSSttttrrrruuuucccctttt structure.
  501.  
  502.      RRRREEEELLLLAAAATTTTEEEEDDDD
  503.           EEEExxxxmmmmSSSSttttrrrriiiinnnnggggTTTTrrrraaaannnnssssffffeeeerrrr(3), XXXXmmmmTTTTrrrraaaannnnssssffffeeeerrrrDDDDoooonnnneeee(3), XXXXmmmmTTTTrrrraaaannnnssssffffeeeerrrrVVVVaaaalllluuuueeee(3),
  504.           XXXXmmmmeeeeCCCClllliiiippppbbbbooooaaaarrrrddddSSSSiiiinnnnkkkk(3), XXXXmmmmeeeeCCCClllliiiippppbbbbooooaaaarrrrddddSSSSoooouuuurrrrcccceeee(3),
  505.           XXXXmmmmeeeeCCCCoooonnnnvvvveeeerrrrttttMMMMeeeerrrrggggeeee(3), XXXXmmmmeeeeDDDDrrrraaaaggggSSSSoooouuuurrrrcccceeee(3), XXXXmmmmeeeeDDDDrrrrooooppppSSSSiiiinnnnkkkk(3),
  506.           XXXXmmmmeeeeGGGGeeeettttEEEEnnnnccccooooddddiiiinnnnggggAAAAttttoooommmm(3), XXXXmmmmeeeePPPPrrrriiiimmmmaaaarrrryyyySSSSiiiinnnnkkkk(3),
  507.           XXXXmmmmeeeePPPPrrrriiiimmmmaaaarrrryyyySSSSoooouuuurrrrcccceeee(3), XXXXmmmmeeeeSSSSeeeeccccoooonnnnddddaaaarrrryyyySSSSiiiinnnnkkkk(3),
  508.           XXXXmmmmeeeeSSSSeeeeccccoooonnnnddddaaaarrrryyyySSSSoooouuuurrrrcccceeee(3), XXXXmmmmeeeeSSSSeeeeccccoooonnnnddddaaaarrrryyyyTTTTrrrraaaannnnssssffffeeeerrrr(3),
  509.           XXXXmmmmeeeeSSSSttttaaaannnnddddaaaarrrrddddCCCCoooonnnnvvvveeeerrrrtttt(3), XXXXmmmmeeeeSSSSttttaaaannnnddddaaaarrrrddddTTTTaaaarrrrggggeeeettttssss(3), and
  510.           XXXXmmmmeeeeTTTTrrrraaaannnnssssffffeeeerrrrAAAAddddddddDDDDoooonnnneeeePPPPrrrroooocccc(3).
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.      Page 8                                         (printed 10/24/98)
  526.  
  527.  
  528.  
  529.